{
 "cells": [
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "89cf2628",
   "metadata": {},
   "source": [
    "# Asym Line Example\n",
    "\n",
    "In this notebook we will present examples of asymmetric lines in `power-grid-model`. \n",
    "\n",
    "Different input formats are covered. We will do one-time power flow calculation and one-time state estimation.\n",
    "\n",
    "This notebook serves as an example of how to use the Python API. For detailed API documentation, refer to\n",
    "[Python API reference](../api_reference/python-api-reference.md)\n",
    "and [Native Data Interface](../advanced_documentation/native-data-interface.md).\n",
    "\n",
    "## Asym Line\n",
    "\n",
    "Asym Line is described as a pi model in `power-grid-model`, and it belongs to the `branch` component type which connects two nodes with possibly different voltage levels.\n",
    "\n",
    "### Example Network\n",
    "\n",
    "We use a simple network with 3 nodes, 1 source, 1 load and 2 asym lines. As shown below:\n",
    "\n",
    "```txt\n",
    "   source_1 --- node_2 --- asym_line_3 --- node_4 --- asym_line_5 --- node_6 --- load_7\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "ae11dc9a",
   "metadata": {},
   "outputs": [],
   "source": [
    "# some basic imports\n",
    "import numpy as np\n",
    "import pandas as pd\n",
    "\n",
    "from power_grid_model import (\n",
    "    CalculationMethod,\n",
    "    CalculationType,\n",
    "    ComponentType,\n",
    "    DatasetType,\n",
    "    LoadGenType,\n",
    "    MeasuredTerminalType,\n",
    "    PowerGridModel,\n",
    "    initialize_array,\n",
    ")"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "f983cef7",
   "metadata": {},
   "source": [
    "### Input Dataset\n",
    "\n",
    "We create an input dataset by using the helper function `initialize_array`. \n",
    "\n",
    "Please refer to [Components](../user_manual/components.md) for detailed explanation of all component types and their input/output attributes."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "6f008736",
   "metadata": {},
   "outputs": [],
   "source": [
    "# node\n",
    "node = initialize_array(DatasetType.input, ComponentType.node, 3)\n",
    "node[\"id\"] = np.array([2, 4, 6])\n",
    "node[\"u_rated\"] = [1e3, 1e3, 1e3]\n",
    "\n",
    "# load\n",
    "asym_load = initialize_array(DatasetType.input, ComponentType.asym_load, 1)\n",
    "asym_load[\"id\"] = [7]\n",
    "asym_load[\"node\"] = [6]\n",
    "asym_load[\"status\"] = [1]\n",
    "asym_load[\"type\"] = [LoadGenType.const_power]\n",
    "asym_load[\"p_specified\"] = [[1000.0, 2000.0, 3000.0]]\n",
    "asym_load[\"q_specified\"] = [[1000.0, 2000.0, 3000.0]]\n",
    "\n",
    "# source\n",
    "source = initialize_array(DatasetType.input, ComponentType.source, 1)\n",
    "source[\"id\"] = [1]\n",
    "source[\"node\"] = [2]\n",
    "source[\"status\"] = [1]\n",
    "source[\"u_ref\"] = [1.0]\n",
    "\n",
    "# asym_line\n",
    "asym_line = initialize_array(DatasetType.input, ComponentType.asym_line, 2)\n",
    "asym_line[\"id\"] = [3, 5]\n",
    "asym_line[\"from_node\"] = [2, 4]\n",
    "asym_line[\"to_node\"] = [4, 6]\n",
    "asym_line[\"from_status\"] = [1, 1]\n",
    "asym_line[\"to_status\"] = [1, 1]\n",
    "asym_line[\"r_aa\"] = [0.6904, 0.6904]\n",
    "asym_line[\"r_ba\"] = [0.0495, 0.0495]\n",
    "asym_line[\"r_bb\"] = [0.6904, 0.6904]\n",
    "asym_line[\"r_ca\"] = [0.0492, 0.0492]\n",
    "asym_line[\"r_cb\"] = [0.0495, 0.0495]\n",
    "asym_line[\"r_cc\"] = [0.6904, 0.6904]\n",
    "asym_line[\"r_na\"] = [0.0495, np.nan]\n",
    "asym_line[\"r_nb\"] = [0.0492, np.nan]\n",
    "asym_line[\"r_nc\"] = [0.0495, np.nan]\n",
    "asym_line[\"r_nn\"] = [0.6904, np.nan]\n",
    "asym_line[\"x_aa\"] = [0.8316, 0.8316]\n",
    "asym_line[\"x_ba\"] = [0.7559, 0.7559]\n",
    "asym_line[\"x_bb\"] = [0.8316, 0.8316]\n",
    "asym_line[\"x_ca\"] = [0.7339, 0.7339]\n",
    "asym_line[\"x_cb\"] = [0.7559, 0.7559]\n",
    "asym_line[\"x_cc\"] = [0.8316, 0.8316]\n",
    "asym_line[\"x_na\"] = [0.7559, np.nan]\n",
    "asym_line[\"x_nb\"] = [0.7339, np.nan]\n",
    "asym_line[\"x_nc\"] = [0.7559, np.nan]\n",
    "asym_line[\"x_nn\"] = [0.8316, np.nan]\n",
    "asym_line[\"c0\"] = [0.32e-9, np.nan]\n",
    "asym_line[\"c1\"] = [0.54e-9, np.nan]\n",
    "asym_line[\"c_aa\"] = [np.nan, 0.3200e-09]\n",
    "asym_line[\"c_ba\"] = [np.nan, 0.5400e-09]\n",
    "asym_line[\"c_bb\"] = [np.nan, 0.3200e-09]\n",
    "asym_line[\"c_ca\"] = [np.nan, 0.7600e-09]\n",
    "asym_line[\"c_cb\"] = [np.nan, 0.5400e-09]\n",
    "asym_line[\"c_cc\"] = [np.nan, 0.3200e-09]\n",
    "asym_line[\"i_n\"] = [1000, 1000]\n",
    "\n",
    "# all\n",
    "input_data = {\n",
    "    ComponentType.node: node,\n",
    "    ComponentType.asym_line: asym_line,\n",
    "    ComponentType.asym_load: asym_load,\n",
    "    ComponentType.source: source,\n",
    "}"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d16f9dea",
   "metadata": {},
   "source": [
    "**We can print the input dataset by converting the numpy array to dataframe.**"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "37749c7c",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "   id  from_node  to_node  from_status  to_status    r_aa    r_ba    r_bb  \\\n",
      "0   3          2        4            1          1  0.6904  0.0495  0.6904   \n",
      "1   5          4        6            1          1  0.6904  0.0495  0.6904   \n",
      "\n",
      "     r_ca    r_cb  ...    x_nn          c_aa          c_ba          c_bb  \\\n",
      "0  0.0492  0.0495  ...  0.8316           NaN           NaN           NaN   \n",
      "1  0.0492  0.0495  ...     NaN  3.200000e-10  5.400000e-10  3.200000e-10   \n",
      "\n",
      "           c_ca          c_cb          c_cc            c0            c1  \\\n",
      "0           NaN           NaN           NaN  3.200000e-10  5.400000e-10   \n",
      "1  7.600000e-10  5.400000e-10  3.200000e-10           NaN           NaN   \n",
      "\n",
      "      i_n  \n",
      "0  1000.0  \n",
      "1  1000.0  \n",
      "\n",
      "[2 rows x 34 columns]\n"
     ]
    }
   ],
   "source": [
    "print(pd.DataFrame(input_data[ComponentType.asym_line]))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "47a9c257",
   "metadata": {},
   "source": [
    "### One-time Power Flow Calculation\n",
    "\n",
    "You can call the method `calculate_power_flow` to do a one-time calculation based on the current network data in the model.\n",
    "\n",
    "For detailed explanation of the arguments, batch calculations and asymmetric calculations, we refer to the [Power Flow Example](./Power%20Flow%20Example.ipynb) and [Asymmetric Calculation Example](./Asymmetric%20Calculation%20Example.ipynb). "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "7bb0f998",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "------node voltage result------\n",
      "            0           1           2\n",
      "0  577.350081  577.349890  577.349692\n",
      "1  577.543188  574.815533  571.914289\n",
      "2  579.346994  570.159376  567.087326\n",
      "------node angle result------\n",
      "              0         1         2\n",
      "0 -2.686835e-07 -2.094396  2.094394\n",
      "1  4.811479e-05 -2.087729  2.097964\n",
      "2  2.919948e-03 -2.079969  2.097696\n"
     ]
    }
   ],
   "source": [
    "# validation (optional)\n",
    "from power_grid_model.validation import assert_valid_input_data\n",
    "\n",
    "assert_valid_input_data(input_data=input_data, calculation_type=CalculationType.power_flow)\n",
    "\n",
    "# construction\n",
    "model = PowerGridModel(input_data)\n",
    "\n",
    "# one-time power flow calculation\n",
    "output_data = model.calculate_power_flow(\n",
    "    symmetric=False, error_tolerance=1e-8, max_iterations=20, calculation_method=CalculationMethod.newton_raphson\n",
    ")\n",
    "\n",
    "# result dataset\n",
    "print(\"------node voltage result------\")\n",
    "print(pd.DataFrame(output_data[ComponentType.node][\"u\"]))\n",
    "print(\"------node angle result------\")\n",
    "print(pd.DataFrame(output_data[ComponentType.node][\"u_angle\"]))"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "682c1c48",
   "metadata": {},
   "source": [
    "### One-time State Estimation\n",
    "Below we present a simple example of state estimation for a network with two asym lines. \n",
    "\n",
    "NOTE: In `power-grid-model`, asym lines belong to `branch` component type, therefore the `measured_terminal_type` of power sensors should be assigned to `MeasuredTerminalType.branch_from/_to`.\n",
    "\n",
    "For detailed explanation of the arguments, batch calculations and asymmetric calculations, we refer to the [State Estimation Example](./State%20Estimation%20Example.ipynb) and [Asymmetric Calculation Example](./Asymmetric%20Calculation%20Example.ipynb)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "f0c8c3e8",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "------node result------\n",
      "             0           1            2\n",
      "0  1000.000001  999.999991  1000.000007\n",
      "1  1000.000019  999.999988   999.999997\n",
      "2  1000.000001  999.999999   999.999999\n"
     ]
    }
   ],
   "source": [
    "# voltage sensor\n",
    "asym_voltage_sensor = initialize_array(DatasetType.input, ComponentType.asym_voltage_sensor, 1)\n",
    "asym_voltage_sensor[\"id\"] = [8]\n",
    "asym_voltage_sensor[\"measured_object\"] = [6]\n",
    "asym_voltage_sensor[\"u_sigma\"] = [1.0]\n",
    "asym_voltage_sensor[\"u_measured\"] = [[1000, 1000, 1000]]\n",
    "\n",
    "# power sensor\n",
    "asym_power_sensor = initialize_array(DatasetType.input, ComponentType.asym_power_sensor, 4)\n",
    "asym_power_sensor[\"id\"] = [9, 10, 11, 12]\n",
    "asym_power_sensor[\"measured_object\"] = [3, 3, 5, 5]\n",
    "asym_power_sensor[\"measured_terminal_type\"] = [\n",
    "    MeasuredTerminalType.branch_from,\n",
    "    MeasuredTerminalType.branch_to,\n",
    "    MeasuredTerminalType.branch_from,\n",
    "    MeasuredTerminalType.branch_to,\n",
    "]\n",
    "asym_power_sensor[\"power_sigma\"] = [500.0, 500.0, 500.0, 500.0]\n",
    "asym_power_sensor[\"p_measured\"] = [[1000, 2000, 3000], [1000, 2000, 3000], [1000, 2000, 3000], [1000, 2000, 3000]]\n",
    "asym_power_sensor[\"q_measured\"] = [[1000, 2000, 3000], [1000, 2000, 3000], [1000, 2000, 3000], [1000, 2000, 3000]]\n",
    "\n",
    "# use components from former input dataset cell.\n",
    "input_data2 = {\n",
    "    ComponentType.node: node,\n",
    "    ComponentType.asym_line: asym_line,\n",
    "    ComponentType.asym_load: asym_load,\n",
    "    ComponentType.source: source,\n",
    "    ComponentType.asym_voltage_sensor: asym_voltage_sensor,\n",
    "    ComponentType.asym_power_sensor: asym_power_sensor,\n",
    "}\n",
    "\n",
    "# validation (optional)\n",
    "from power_grid_model.validation import assert_valid_input_data\n",
    "\n",
    "assert_valid_input_data(input_data=input_data2, calculation_type=CalculationType.state_estimation)\n",
    "\n",
    "# construction\n",
    "model2 = PowerGridModel(input_data2)\n",
    "\n",
    "# one-time state estimation\n",
    "output_data2 = model2.calculate_state_estimation(\n",
    "    symmetric=False, error_tolerance=1e-8, max_iterations=20, calculation_method=CalculationMethod.iterative_linear\n",
    ")\n",
    "\n",
    "# result dataset\n",
    "print(\"------node result------\")\n",
    "print(pd.DataFrame(output_data2[ComponentType.node][\"u\"]))"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "venv",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.13.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}